Technotools

home *** CD-ROM | disk | FTP | other *** search

/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / scrn11 / scrnlib.doc < prev next >

Wrap

Text File | 1987-06-30 | 37KB | 1,066 lines

SCRNLIB By Dave Millis P.O. Box 2371 Glenview, Illinois 60025 Copyright 1987 by Dave Millis. All rights reserved 2 SCRNLIB release 1 INTRODUCTION SCRNLIB is a library of text screen routines for the Micro- soft and Turbo C compilers. Most of the routines were written in assembly language for the optimum in speed and performance. These routines remedy some of the deficiencies of C by allowing screen output in color and allowing for the use of windows. I was a Turbo Pascal user for two years before I started to program heavily in C on the PC. In February 1987, I purchased the Microsoft 'C' Compiler 4.0. I always appreciated the flexibility and sheer power of C, but I missed the many simple text output functions of Turbo Pascal. I then decided to write the functions I needed. After working on this part-time for several months I collected all the routines into a file called SCRNLIB.LIB. These routines were tested by several friend and co-workers who offered some constructive criticism and suggestions. They even found a couple of bugs. With the correction of the bugs; the addition of some procedures; and some minor modifications so the routines will work with both Turbo C and the Microsoft 'C' Compiler, SCRNLIB release 1 was completed. I am an active programmer and I have a bachelor's degree in computer science. I am now primarily using C and assembly and I generate a multitude of routines that can be beneficial to many programmers. I am using SCRNLIB to see if there is an interest in these fast, efficient routines. If there is, later versions will include more direct memory access screen procedures, more sophisticated windowing, and many other helpful routines. By now you might be asking- DO I NEED SCRNLIB? Well, I feel SCRNLIB is the best way to output text to the screen with a color attribute. By "color attribute" I mean the method that the characters are displayed on the screen. For monochrome display cards, this means underlined, bold, and inverse video text. The C programming langauge does not provide these functions in a nice workable way. One can use ANSI to help with screen manipulations, however this would require ANSI.SYS be installed on every machine using these programs and the output would be slower than if SCRNLIB was used. The SCRNLIB routines do not require ANSI.SYS be installed and should run on all systems with standard video hardware (ie. MA, HMA, CGA, EGA) including most third party video boards. Since these routines were written in assembly, they run as fast as possible. There is no doubt that other software producers will develope libraries or C source code collections that will allow for some of these same functions; however, If they are not written in assembly, they Software and Documentation Copyright 1987 by Dave Millis 3 SCRNLIB release 1 will not be as fast as SCRNLIB's routines. SCRNLIB also allows other input/output operations. For example, inpstr is a function that enables string inputs from the keyboard. This function is necessary because the input functions in standard C does not allow echoing of the input with the currently set color attribute. If Windows are desired, SCRNLIB provides a great way to generate and maintain them. WINDOWING SCRNLIB provides for a specified area of the screen to be the only area written to or effected by many screen operations. The area, referred to from now on as the active window, is easily defined and "remembered" by the program. Once defined, the active window can be cleared, written to, and scrolled up and down using the normal screen functions provided in SCRNLIB without effecting the rest of the screen. Output functions, such as printsh and putsch, continue output at the beginning of the next line of the active window when the right end of the active window is encountered. The windows can also be saved and restored later anywhere on the screen. Window Example: Say you want to open a window 30 x 5 characters in size to display a message and ask for input from the user of your program. Lets also say you want this window to disappear and restore the screen to its original condition when you're done with it. This is what you would do: 1) Save the current screen below where the window will go. This is done with the scrnsav command: int x; /*number of char. in the input string*/ char undrwindo[152]; /*define a character string large enough to save the screen in*/ --> scrnsav(undrwindo,25,10,54,14); /*save portion of screen */ getpos(); /* read current cursor position (into global variables xposn and yposn */ see the Command section for a full explanation of all commands 2) Next, set the active window: window(25,10,54,14,0);/*declare active window w/ no border*/ 3) To have this window stand out from the rest of the screen, we Software and Documentation Copyright 1987 by Dave Millis 4 SCRNLIB release 1 will change the foreground and background color attributes: setattr(1,4); /* blue on red */ cls(); gotoxy(27,12); This sets the color attribute, clears the 30 x 5 active screen and positions the cursor over 2 and down 2 form the top left corner of the window. At this point the screen looks unchanged except for a 30 x 5 red square in the center. 4) Writing the message is straight forward: printsh("What is your mother's maiden name? "); This is not the best way to present this message, but it illustrates how the windows work. The problem is the message is longer than the width of the screen. What happens is the sentence up through "maiden" is printed, then "name? " is printed on the next line starting at 25,13. 5) Input is handled with the inpstr function: x=inpstr(mommaname); 6) Finally, now that we have the information we require, we need to restore the screen to its original condition and position to its old position: scrnrst(undrwindo,25,10); gotoxy(xposn,yposn); While windows are not an extensively used function in a lot of programs, the functions in SCRNLIB provides a lot of practical applications. For example, If you want to generate a program that actively uses the entire screen except for the 25 row where the function keys or other information is always displayed, an active window 80 x 24 can be defined. This way only the top 24 rows will be written to and when the bottom of the active window is reached the top 24 rows will scroll up, leaving row 25 unchanged. USING SCRNLIB WITH TURBO-C When compiling a program in the integrated environment, SCRNLIBx.LIB must be specified in a project file. For example, to run DEMO.C with the small memory model, DEMO.PRJ would look like: Software and Documentation Copyright 1987 by Dave Millis 5 SCRNLIB release 1 DEMO \TURBOC\LIB\SCRNLIBS.LIB (assuming that the SCRNLIBx libraries are in the \TURBOC\LIB directory) MORE TECHNICAL INFORMATION In release 1, all but three of the routines were written in assembly, using the Microsoft Macro Assembler 4.0. In the interest of speed and efficiency, the error checking was kept to a minimum, as is typical of C. It is up to the programmer to make sure that the proper variables are passed and the proper amount of memory is allocated for the arrays used. See the section of commonly made errors for an explanation of the errors most often made in using SCRNLIB. In all routines that require an X and Y location, it must be noted that the top left corner of the screen is 0,0 (not 1,1). This means the bottom right corner is 79,24. There are several global variables used by SCRNLIB that are accessible to the programmer too: oldcurs, scxlow, scxhigh, scylow, scyhigh, txtattr, xposn and yposn. These keywords should not be used in other contexts. There exact meanings are as follows: oldcurs contains the start and stop scan lines of the cursor saved with the cursoff function and used by the curson function. It is uninitialized at the start. scxlow and scylow define the upper left corner of the active window. scxhigh and scyhigh define the location of the lower right corner of the active window. The default values defined in the header file are: scxlow=0, scylow=0, scxhigh=79, scyhigh=24; this is just the entire screen. These values can be changed individually in a program, or through the window command. txtattr contains the current text color attribute (default is 07). xposn and yposn are the current X and Y position of the cursor set when the function getpos is executed. These variables, along with the getpos function, exist for the use of the programmer to easily get the cursor location. xposn and yposn are only changed by the getpos function and therefore can be used to store the cursor location. Software and Documentation Copyright 1987 by Dave Millis 6 SCRNLIB release 1 COMMONLY MADE ERROR WITH SCRNLIB 1) Probably the most common problem results from not declar- ing string variables large enough to hold all the data put in them. This over writes other portions of the program and causes it to crash. This usually occurs with the scrnsav function and one should carefully read about this function before using it. 2) A stack overflow is a common problem when numerous screen saves are preformed. This is because many local variables are stored in the stack area and the screen data strings are very large. This problem is also not detected using the default settings in Turbo-C. If your program behaves peculiarly, turn on the stack overflow checking in the Code generation menu in the Options-Compiler menu. The easiest way to correct this problem is to use global arrays (ie. declare the arrays outside of any functions-this includes function main). If the arrays aren't too large, you can use the MS link and use the /stack option to increase the size of the stack. I have not had success using EXEMOD to increase the size of the stack on Turbo-C (TLINK linked) files with the stack overflow checking on. 3) Trying to address the last column or the last row of the screen with 80 or 25 respectively does not work since the bottom right corner is 79,24. This is because the first column and the first row are both defined as zero (0). 4) Forgetting to include the SCRNLIB.H file at the beginning of the program can cause problems. DISCLAIMER I do not guarantee that the SCRNLIB functions will do anything. However, I have tried to write the best, most effi- cient, and most portable functions that I could, and have tested them extensively on eight different makes and models of MS-DOS based microcomputers. I also do not guarantee that SCRNLIB will not do anything harmful to anything nor anybody. Any discrep- ancies or problems should be brought to my attention so that I could improve upon them before the next release. At this time, I believe SCRNLIB is in perfect working condition. THE USERS OF SCRNLIB ARE SOLELY RESPONSIBLE ITS EFFECTS IN THEIR CODE. TRADE MARKS Turbo Pascal and Turbo C are registered trade marks of Borland International, Inc. MS-DOS, MS, Microsoft, and Microsoft 'C' Compiler are a registered trade mark of Microsoft Corp. Software and Documentation Copyright 1987 by Dave Millis 7 SCRNLIB release 1 REFERENCE Even though these routines were written in assembly they conform to the C calling standard and are used as normal C procedures and functions. The names have been chosen to describe the function and so they appear as a natural extension of the C language. ************************** beep PROTOTYPE: void beep(void); DESCRIPTION: I admit this is a very unimpressive procedure to start with, but I do use it quite often. This routine simply sound the standard 800 Hz sound for 1/4 seconds. ************************** cls PROTOTYPE: void cls(void); DESCRIPTION: This clears the active screen using the current attributes. ************************** cursoff PROTOTYPE: void cursoff(void); DESCRIPTION: This turns off the cursor and saves the old cursor type in the global variable oldcurs. This allows for the old cursor to be restored. Also allowed is the ability to turn off the cursor then change to a different form of cursor, using setcurs, then use curson to restore the original cursor. Remember that cursoff must be executed before curson will restore the old cursor. also see: curson,setcurs Software and Documentation Copyright 1987 by Dave Millis 8 SCRNLIB release 1 ************************** curson PROTOTYPE: void curson(void); DESCRIPTION: Restore the cursor stored in the global variable oldcurs. also see: cursoff,setcurs ************************** getkey PROTOTYPE: char getkey(void); DESCRIPTION: This get a character from the keyboard. ************************** getpos PROTOTYPE: void getpos(void); DESCRIPTION: Gets the current position of the cursor and puts the X and Y positions in the global variables xposn and yposn respectively. These two variables, xposn and yposn, are only affected by this function (and a direct assignment), so they can be used to reference the position where getpos was last executed. Software and Documentation Copyright 1987 by Dave Millis 9 SCRNLIB release 1 ************************** gotoxy PROTOTYPE: void gotoxy(int xloc,int yloc); DESCRIPTION: gotoxy positions the cursor at the screen position defined by xloc and yloc. The X position and Y position are xloc and yloc respectively. This function is not limited by the active screen. ************************** inpstr PROTOTYPE: int inpstr(char *str); DESCRIPTION: inpstr gets a string input from the keyboard and echoes the input on the screen using the current attributes. The string of input is stored in *str. The returned integer is the number of characters entered. ************************** keywait PROTOTYPE: char keywait(void); DESCRIPTION: keywait clears the keyboard then waits for a single keystroke from the keyboard. The returned character is the ASCII value of the first byte of input from the key board. If the key pressed is a special function key, such as the function keys or the arrow keys, the return character will be 00h. Since these special keys input a series of two characters, a character will remain in the keyboard buffer and the function getkey can be used to get the second character. Software and Documentation Copyright 1987 by Dave Millis 10 SCRNLIB release 1 ************************** movxy PROTOTYPE: void movxy(int xdis,int ydis); DESCRIPTION: This moves the cursor vertically and horizontally from its current position. xdis and ydis are the displacements from the current cursor position in the X and Y position respectively. ************************** printmch PROTOTYPE: void printmch(char *chr,int numprn); DESCRIPTION: printmch prints a single character a specified number of times horizontally on the screen using the current attributes. If the number of characters exceeds the space to the right side of the screen the remaining characters will rap around the beginning of the next line. If the printing proceeds to the bottom right corner of the screen, the screen will not scroll and the remaining characters will not be printed. This procedure is not limited by the active screen. *chr is the character to be printed and numprn is the number of times *chr is to be printed. This function, along with printmcv, was primarily written to draw frames and lines on the screen, usually outside the active screen. printmch, along with all the printing routines, uses the BIOS to output to the screen. In future releases, there will be the option of doing output using the BIOS or direct memory access. There will be a global variable that will dictate which method is to be used. This variable can be changed in the program, so a command line option can be added to your programs to set the output method. also see: printmcv Software and Documentation Copyright 1987 by Dave Millis 11 SCRNLIB release 1 ************************** printmcv PROTOTYPE: void printmcv(char *chr, int numprn); DESCRIPTION: printmcv prints a single character a specified number of times vertically on the screen using the current attributes. If the number of characters exceeds the space to the down the rest of the screen, the remaining characters are not printed. *chr is the character to be printed and numprn is the number of times *chr is to be printed. This procedure is not limited by the active screen. This function, along with printmch, was primarily written to draw frames and lines on the screen, usually outside the active screen. also see:printmcv ************************** printsh PROTOTYPE: void printsh(char *str); DESCRIPTION: printsh prints a string horizontally in the active window using the current attributes. If the end of the active window is reached, the string continues on the next line of the active window. If the end of the active window is reached the window will scroll up and the rest of the string will be printed. All of the back slash (\) functions are supported as they are in the standard C printf procedure; however, the % functions for printing numbers and other strings are not supported yet. To generate output in the same fashion as printf the sprintf function can be used alone with printsh: sprintf(txt,"a=%d b=%d",a,b); printsh(txt); Remember to include stdio.h when using sprintf. Support for numbers and additional strings is currently one of my primary projects. also see printsv,putsch Software and Documentation Copyright 1987 by Dave Millis 12 SCRNLIB release 1 ************************** printsv PROTOTYPE: void printsv(char *str); DESCRIPTION: printsv prints the given string vertically in the active screen using the current attributes. If there is not a enough space from the current cursor position to the bottom of the window the remainder of the string is truncated. The only back slash commands supported are the \a and \b. Like the printsh routine, the % format specifications are not supported, yet. also see printsh,putsch ************************** putsch PROTOTYPE: void putsch(char *chr); DESCRIPTION: putsch prints a single character at the cursor position with the current attribute. This function only works in the active window and advances to the next line of the active window after printing a character in the last active column. All the back slash commands are supported. also see printsh,printsv ************************** scrldn PROTOTYPE: void scrldn(int); DESCRIPTION: scrldn scrolls the active screen down the number of rows specified by int. The current background attribute is used for the blank lines added to the top of the screen as the screen scrolls. also see scrlup Software and Documentation Copyright 1987 by Dave Millis 13 SCRNLIB release 1 ************************** scrlup PROTOTYPE: void scrlup(int); DESCRIPTION: scrlup scrolls the active screen up the number of rows specified by int. The current background attribute is used for the blank lines added to the bottom of the screen. also see scrldn ************************** scrnoff PROTOTYPE: void scrnoff(); DESCRIPTION: scrnoff blanks the screen. also see scrnon ************************** scrnon PROTOTYPE: void scrnon(); DESCRIPTION: scrnon turns the screen back on after a scrnoff has been executed. also see scrnoff Software and Documentation Copyright 1987 by Dave Millis 14 SCRNLIB release 1 ************************** scrnrst PROTOTYPE: void scrnrst(char *str,int xl,int yl); DESCRIPTION: scrnrst restores a saved screen that was saved with scrnsav or scrnsavd. str is the character array that stores the screen information, xl and yl makeup the x and y position of the top left corner of where the window is to be restored. scrnrst(d) can also be used with scrnsav(d) to move windows. A window or an area of the screen can be saved and then restored at a different location by specifying a different xl and yl in the restore cammand. The dimensions of the screen remain the same as they are stored in the data string. also see scrnrstd,scrnsav,scrnsavd ************************** scrnrstd PROTOTYPE: void scrnrstd(char *str,int xl,int yl); DESCRIPTION: scrnrstd works exactly like scrnrst. The only difference is that scrnrstd uses direct memory access to restore the screen. This provides a great speed enhancement over scrnrst, which uses the BIOS, but it may not be as portable to other computers. also see scrnrst,scrnsav,scrnsavd Software and Documentation Copyright 1987 by Dave Millis 15 SCRNLIB release 1 ************************** scrnsav PROTOTYPE: void scrnsav(chr *str,int xl,int yl,int xh,int yh); DESCRIPTION: scrnsav saves a rectangular portion of the screen. The information from this portion of the screen is stored in the character string str. xl and yl define the upper left corner and xh and yh define the lower right corner of the rectangle. Calculation to determine the size of *str: size = (2 x (xh - xl + 1) x (yh - yl + 1)) + 2) This is simply the size of the window times 2, plus 2. The reason for this is 2 bytes must be stored for each character on the screen, one for the character and one for the attribute, then the first 2 bytes of the string contain the size of the array (more specifically the X size and Y size). It is VERY important that *str is large enough to hold all the data. Unpredictable results will occur if this space is too small. It does not make any difference if this space is too large. also see scrnrst,scrnrst,scrnsavd ************************** scrnsavd PROTOTYPE: void scrnsavd(chr *str,int xl,int yl,int xh,int yh); DESCRIPTION: scrnsavd works exactly like scrnsav. The only difference is that scrnsavd uses direct memory access to save the screen. This provides a great speed enhancement over scrnsav, which uses the BIOS, but it may not be as portable to other computers. also see scrnrst,scrnrstd,scrnsav Software and Documentation Copyright 1987 by Dave Millis 16 SCRNLIB release 1 ************************** setattr PROTOTYPE: void setattr(int fgrnd,int bgrnd); DESCRIPTION: setattr sets the current color attribute to be used for the screen output functions. fgrnd is an integer from 0-15 that specfies the foreground color. These numbers correspond to: 0 - Black 8 - Gray 1 - Blue (underline) 9 - Bright Blue (bright underline) 2 - Green 10 - Bright Green 3 - Cyan 11 - Bright Cyan 4 - Red 12 - Bright Red 5 - Magenta 13 - Bright Magenta 6 - Brown 14 - Yellow or Bright Brown 7 - White 15 - Bright White The descriptions in parentheses are for monochrome cards. bgrnd is an integer also from 0-15 where 0-7 specifies the background color. 0-7 correspond to the same colors as the foreground colors above. 8-15 correspond to a the same background color as 0-7 respectively, but causes the foreground color to blink. ************************** setcurs PROTOTYPE: void setcurs(int curstrt, int curstop); DESCRIPTION: setcurs set the cursor type. curstrt is the first scan line and curstop is the final scan line that makes up the cursor. The cursor is defined by the number and positions of lines that make it up. For example, the cursor on a CGA is made up of lines 6 and 7 (curstrt=6, curstop=7). A box cursor on a CGA would be: curstrt=0, curstop=7. The total number of line on a monochrome is 14 (0-13). If curstrt is larger than curstop, the scan lines will wrap around and the cursor will appear as two sets of lines. also see cursoff,curson Software and Documentation Copyright 1987 by Dave Millis 17 SCRNLIB release 1 ************************** window PROTOTYPE: void window(int xl,xin yl,int xh,int yh,int brdrtype); DESCRIPTION: window sets the active window. xl and yl define the top left corner and xh and yh are the lower right corner of the window. brdrtype is the type of border that will be drawn around the window: 0 is no border, 1 is a single line boarder, and 2 is a double line border. This border is drawn OUTSIDE of the active screen. This means that if a border is specified, the total boundaries of the screen will be: xl-1,yl-1,xh+1,yh+1. One word of warning, do not try and draw a border around a window that has an edge of the ACTIVE screen as one of its borders. This will usually cause the border to be printed at the other edge of the screen (It wraps around). Software and Documentation Copyright 1987 by Dave Millis 18 SCRNLIB release 1 REGISTRATION I wrote SCRNLIB with the purpose of making programming a little bit easier and a little bit more fun. With this in mind, I would like to encourage everyone who uses SCRNLIB to freely copy it and upload it to other bulletin boards providing that: 1) No fee is charged for such copying and distribution and 2) SCRNLIB is distributed ONLY in its ORIGINAL form, unmodified in anyway. I do ask, however, that those who find SCRNLIB useful become registered users and obtain a license for its use. Only registered users may use SCRNLIB in the development of their own programs and may sell or distribute these programs to others. Registered users will also receive technical support and will be informed of any major developments and improvements. To register, just send $10 along with the attached registration form and in return I will mail you : 1) the Latest Version of SCRNLIB including libraries that work with each of the Small, Medium, Compact, and Large memory modules. 2) The Latest Documentation. If you try SCRNLIB and feel it's not quite for you, please still send us your opinion of the product and any suggestions. I welcome and encourage any input anyone has. ________________________________________________________________ cut along dashed line and mail with check for $10 per license and $1 postage and shipping for each disk requested to DAVE MILLIS PO BOX 2371, GLENVIEW, ILLINOIS 60025 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - I HAVE ENCLOSED $_______ FOR _____ COPIES OF SCRNLIB TO BE REGISTERED TO: NAME_______________________________ COMPANY____________________________ ADDRESS________________________________________________________ CITY_______________________________ STATE__________ ZIP CODE____________ PHONE ( )______________________ ( )_______________________ CURRENT RELEASE IN YOUR POSSESSION _________ ___ PLEASE CONTACT ME ABOUT QUANTITY PRICING OR SITE LICENSING. Copyright 1987 by Dave Millis. All rights reserved. 19 SCRNLIB release 1 FUTURE RELEASES All the printing routines use the BIOS to output to the screen. In future releases, there will be the option of doing output using the BIOS or direct memory access. There will be a global variable that will dictate which method is to be used. This variable can be changed in the program, so a command line option can be added to your programs to set the output method. I currently have several more functions that I have not tested thoroughly enough yet to include with this release. They include functions that: set the border color; check and set the video mode (SCRNLIB functions work in 40 character mode also); allow for a max number of characters to be input with the string input function; support more sophisticated windowing; ... and many more. Copyright 1987 by Dave Millis. All rights reserved.